From 0f2caded42beafb40ca4ddf3d5f8e4c0098d317e Mon Sep 17 00:00:00 2001 From: "Carol (Nichols || Goulding)" Date: Fri, 13 May 2016 19:42:01 -0400 Subject: [PATCH] Link crates.io everywhere --- src/doc/crates-io.md | 26 +++++++++++++------------- src/doc/faq.md | 8 +++++--- src/doc/specifying-dependencies.md | 14 ++++++++------ 3 files changed, 26 insertions(+), 22 deletions(-) diff --git a/src/doc/crates-io.md b/src/doc/crates-io.md index 552971124..ee9a72985 100644 --- a/src/doc/crates-io.md +++ b/src/doc/crates-io.md @@ -2,7 +2,7 @@ Once you've got a library that you'd like to share with the world, it's time to publish it on [crates.io]! Publishing a crate is when a specific -version is uploaded to be hosted on crates.io. +version is uploaded to be hosted on [crates.io]. Take care when publishing a crate, because a publish is **permanent**. The version can never be overwritten, and the code cannot be deleted. There is no @@ -27,13 +27,13 @@ immediately. # Before publishing a new crate -Keep in mind that crate names on crates.io are allocated on a first-come-first- +Keep in mind that crate names on [crates.io] are allocated on a first-come-first- serve basis. Once a crate name is taken, it cannot be used for another crate. ## Packaging a crate The next step is to package up your crate into a format that can be uploaded to -crates.io. For this we’ll use the `cargo package` subcommand. This will take +[crates.io]. For this we’ll use the `cargo package` subcommand. This will take our entire crate and package it all up into a `*.crate` file in the `target/package` directory. @@ -79,7 +79,7 @@ include = [ ## Uploading the crate Now that we’ve got a `*.crate` file ready to go, it can be uploaded to -crates.io with the `cargo publish` command. And that’s it, you’ve now published +[crates.io] with the `cargo publish` command. And that’s it, you’ve now published your first crate! ```notrust @@ -104,7 +104,7 @@ and run `cargo publish` to upload the new version. # Managing a crates.io-based crate Management of crates is primarily done through the command line `cargo` tool -rather than the crates.io web interface. For this, there are a few subcommands +rather than the [crates.io] web interface. For this, there are a few subcommands to manage a crate. ## `cargo yank` @@ -125,7 +125,7 @@ those secrets immediately. The semantics of a yanked version are that no new dependencies can be created against that version, but all existing dependencies continue to work. One of the -major goals of crates.io is to act as a permanent archive of crates that does +major goals of [crates.io] is to act as a permanent archive of crates that does not change over time, and allowing deletion of a version would go against this goal. Essentially a yank means that all projects with a `Cargo.lock` will not break, while any future `Cargo.lock` files generated will not list the yanked @@ -151,7 +151,7 @@ full rights to the crate. In addition to being able to publish or yank versions of the crate, they have the ability to add or remove owners, *including* the owner that made *them* an owner. Needless to say, you shouldn’t make people you don’t fully trust into a named owner. In order to become a named owner, a user -must have logged into crates.io previously. +must have logged into [crates.io] previously. If a team name is given to `--add`, that team becomes a “team” owner, with restricted right to the crate. While they have permission to publish or yank @@ -169,7 +169,7 @@ Team membership is not something GitHub provides simple public access to, and it is likely for you to encounter the following message when working with them: > It looks like you don’t have permission to query a necessary property from -GitHub to complete this request. You may need to re-authenticate on crates.io +GitHub to complete this request. You may need to re-authenticate on [crates.io] to grant permission to read GitHub org memberships. Just go to https://crates.io/login @@ -190,9 +190,9 @@ as an owner, or publish a crate as a team owner. If you ever attempt to do this, you will get the error above. You may also see this error if you ever try to publish a crate that you don’t own at all, but otherwise happens to have a team. -If you ever change your mind, or just aren’t sure if crates.io has sufficient +If you ever change your mind, or just aren’t sure if [crates.io] has sufficient permission, you can always go to https://crates.io/login, which will prompt you -for permission if crates.io doesn’t have all the scopes it would like to. +for permission if [crates.io] doesn’t have all the scopes it would like to. An additional barrier to querying GitHub is that the organization may be actively denying third party access. To check this, you can go to: @@ -204,12 +204,12 @@ something like: ![Organization Access Control](images/org-level-acl.png) -Where you may choose to explicitly remove crates.io from your organization’s +Where you may choose to explicitly remove [crates.io] from your organization’s blacklist, or simply press the “Remove Restrictions” button to allow all third party applications to access this data. -Alternatively, when crates.io requested the `read:org` scope, you could have -explicitly whitelisted crates.io querying the org in question by pressing +Alternatively, when [crates.io] requested the `read:org` scope, you could have +explicitly whitelisted [crates.io] querying the org in question by pressing the “Grant Access” button next to its name: ![Authentication Access Control](images/auth-level-acl.png) diff --git a/src/doc/faq.md b/src/doc/faq.md index 6bab5e4ce..ae7e9bcaa 100644 --- a/src/doc/faq.md +++ b/src/doc/faq.md @@ -2,7 +2,7 @@ # Is the plan to use GitHub as a package repository? -No. The plan for Cargo is to use crates.io, like npm or Rubygems do with +No. The plan for Cargo is to use [crates.io], like npm or Rubygems do with npmjs.org and rubygems.org. We plan to support git repositories as a source of packages forever, @@ -15,7 +15,7 @@ We think that it’s very important to support multiple ways to download packages, including downloading from GitHub and copying packages into your project itself. -That said, we think that crates.io offers a number of important benefits, and +That said, we think that [crates.io] offers a number of important benefits, and will likely become the primary way that people download packages in Cargo. For precedent, both Node.js’s [npm][1] and Ruby’s [bundler][2] support both a @@ -130,7 +130,7 @@ picture to decide what versions of dependencies should be used. # Can libraries use `*` as a version for their dependencies? -**Starting January 22nd, 2016, crates.io will begin rejecting packages with +**Starting January 22nd, 2016, [crates.io] will begin rejecting packages with wildcard dependency constraints.** While they _can_, strictly speaking, they should not. A version requirement @@ -153,3 +153,5 @@ Cargo does not allow other names such as `cargo.toml` or `Cargofile` to emphasize the ease of how a Cargo repository can be identified. An option of many possible names has historically led to confusion where one case was handled but others were accidentally forgotten. + +[crates.io]: https://crates.io/ diff --git a/src/doc/specifying-dependencies.md b/src/doc/specifying-dependencies.md index f0f8365bb..495b12c18 100644 --- a/src/doc/specifying-dependencies.md +++ b/src/doc/specifying-dependencies.md @@ -1,6 +1,6 @@ % Specifying Dependencies -Your crates can depend on other libraries from crates.io, git repositories, or +Your crates can depend on other libraries from [crates.io], git repositories, or subdirectories on your local file system. You can also temporarily override the location of a dependency-- for example, to be able to test out a bug fix in the dependency that you are working on locally. You can have different @@ -9,7 +9,7 @@ development. Let's take a look at how to do each of these. # Specifying Dependencies from crates.io -Cargo is configured to look for dependencies on `crates.io` by default. Only +Cargo is configured to look for dependencies on [crates.io] by default. Only the name and a version string are required in this case. In [the cargo guide](guide.html), we specified a dependency on the `time` crate: @@ -155,8 +155,8 @@ in the `hello_utils` folder (relative to the `Cargo.toml` it’s written in). And that’s it! The next `cargo build` will automatically build `hello_utils` and all of its own dependencies, and others can also start using the crate as well. However, crates that use dependencies specified with only a path are not -permitted on crates.io. If we wanted to publish our `hello_world` crate, we -would need to publish a version of `hello_utils` to crates.io (or specify a git +permitted on [crates.io]. If we wanted to publish our `hello_world` crate, we +would need to publish a version of `hello_utils` to [crates.io] (or specify a git repository location) and specify its version in the dependencies line as well: ```toml @@ -190,7 +190,7 @@ $ git clone https://github.com/conduit-rust/conduit.git ``` You’d like to have `conduit-static` use your local version of `conduit`, -rather than the one on crates.io, while you fix the bug. +rather than the one on [crates.io], while you fix the bug. Cargo solves this problem by allowing you to have a local configuration that specifies an **override**. If Cargo finds this configuration when @@ -226,7 +226,7 @@ this instance, we’re just adding `conduit`, so it will be the only one that’ overridden. This path must be an absolute path. Note: using a local configuration to override paths will only work for crates -that have been published to crates.io. You cannot use this feature to tell Cargo +that have been published to [crates.io]. You cannot use this feature to tell Cargo how to find local unpublished crates. More information about local configuration can be found in the [configuration @@ -302,3 +302,5 @@ example: [target.'cfg(unix)'.dev-dependencies] mio = "0.0.1" ``` + +[crates.io]: https://crates.io/ -- 2.30.2